22 实践课-工业级 AI 智能体架构设计

工业级 AI 智能体架构设计

关联：索引

术语小抄（初学者版）

作业：布置（见文末）

1）工业级智能体的三段式不是“概念”，是“可交付模块”

2）所有模块接口必须回答 6 个问题（接口六问）

  1. 输入字段是什么？哪些必填？哪些可选？范围/枚举是什么？
  2. 输出字段是什么？成功/失败分别长什么样？
  3. 失败语义是什么？（错误码、是否可重试、是否需要人工介入）
  4. 超时/重试策略是什么？（谁负责重试？最多几次？退避策略？）
  5. 幂等性如何保证？（同一个请求重复执行会不会造成副作用）
  6. 如何追踪与审计？（trace_id、request_id、事件日志、回执）

3）架构图最小信息集（画图不跑偏）

一张合格的架构图至少包含：

AI 工具使用：架构初稿生成 / 接口契约优化 / 架构图审计（学生可直接复制）

使用方法：把你们的“场景描述、已知数据源、执行系统、规则约束、风险点”粘贴到 {你的内容}。要求 AI 先产出结构化清单，再产出图和契约表。你必须进行人工审计与回归校验，不可直接照搬。

模板目录：

模板 1：工业级智能体架构原则思维导图（清单版）

你是工业级AI智能体架构师。请围绕“感知-决策-执行”架构，输出一份可教学的思维导图（用分级清单表示，不要画图），必须包含：
1）模块划分原则（边界、职责、可替换性）
2）接口设计原则（输入输出契约、错误语义、trace_id、幂等与重试）
3）可靠性原则（降级、兜底、人工接管、回放）
4）安全与合规（最小权限、审计、敏感数据处理）
5）绿色制造视角（节能减耗、效率提升、避免无效调用/空转）

输出要求：
- 只输出<<<MINDMAP>>>...<<<END_MINDMAP>>>，用最多4层缩进。

我的材料：{你的内容}

解释与自检：

模板 2：分拣场景三段式架构图（Mermaid）

你是分拣场景智能体架构设计师。请基于我的材料输出一个 Mermaid flowchart 架构图，必须包含：
- 感知层：分拣数据采集、指令解析、数据校验与归一化
- 决策层：意图识别、规则匹配、任务规划/路由、澄清/二次确认、异常处理
- 执行层：任务下发、设备控制（机械臂/输送线）、执行回执、状态查询
- 横切能力：权限与安全门禁、审计日志、可观测性（trace_id贯穿）、回放与复盘入口

输出要求：
- 只输出<<<MERMAID>>>...<<<END_MERMAID>>>，不要解释文字。

我的材料：{你的内容}

解释与自检：

模板 3：模块接口契约表（可落地、可测试）

你是智能体落地工程师。请为“分拣场景智能体”的感知/决策/执行三个层级输出接口契约表（Markdown表格），列必须包含：
模块 | 子模块 | 输入(字段:类型/约束) | 输出(字段:类型) | 失败返回(错误码/是否可重试) | 幂等与超时 | 审计字段(trace_id等)

要求：
1）每层至少2个子模块；
2）字段要可校验（枚举/范围/必填/可选写清楚）；
3）失败返回要工程化（不要只写“失败”）；
4）至少给出3条“常见异常”并说明落在哪个模块处理最合适。

材料：{你的内容}

解释与自检：

模板 4：审计与改进学生架构图（接口问题导向）

你是课堂项目的技术评审。下面是一份学生的“智能体架构图（文字描述版）+ 接口表（简版）”。请输出：
1）<<<ISSUES>>>：按严重度排序的问题清单（每条说明影响：会导致什么故障/越权/不可测试）
2）<<<PATCHES>>>：最小改动建议（能直接替换进文档的句子/表格行）
3）<<<CHECKLIST>>>：回归验证清单（至少8条，包含缺信息、冲突、注入干扰、执行超时、设备回执丢失、权限不足）

输出要求：
- 三段格式必须严格包含ISSUES/PATCHES/CHECKLIST标记；
- 不要输出长段散文。

材料：{你的内容}

填写说明（学生按顺序完成）：

工作表 1：模块划分卡（感知/决策/执行）

层级 子模块 做什么（职责） 不做什么（边界） 关键输入 关键输出
感知




决策




执行




工作表 2：架构图自检清单（画完必查）

检查项 通过标准（是/否） 备注
系统边界清晰 内部模块与外部系统有边界线，数据流进出明确
横切能力存在 权限、审计、trace_id贯穿、回放入口都有位置
失败兜底可见 缺信息/冲突/超时/设备失败有路径或处理点
模块不过载 单模块职责不超过3条，避免“万能模块”
可测试性说明 每层至少有1个可测试回归点（输入输出可复现）

工作表 3：接口契约表（可落地）

模块 接口名 输入（字段:类型/约束） 输出（字段:类型） 错误码与可重试 trace_id 与审计
感知




决策




执行




工作表 4：标注数据流图（从感知到决策）

要求：用“数据表/文件/事件流”的方式描述数据流，不要只写一句“进入训练”。

数据对象 来源（感知层） 处理/标注 去向（决策层） 追溯字段（必填）
指令样本（raw_text）


trace_id / sample_id / ts_ms
槽位标注（slots）


labeler_id / version
意图标注（intent）


guideline_version
规则命中（rule_hit）


rule_id
  1. 你们上一讲写的智能体流程，如果增加一个新执行系统（例如换机械臂厂商），你要改哪里？为什么？
  2. 如果发生一次误控（动作下发错了），你如何复盘：是谁触发的、走了哪条决策、调用了哪个工具、参数是什么？

把“工业级”落到 6 条可检查原则（写在图上/表里，而不是只背概念）：

  1. 边界清晰：每个模块写“做什么/不做什么”，避免职责漂移。
  2. 契约先行：先定义输入输出与失败语义，再写实现（避免后期接口反复返工）。
  3. 可回放：关键决策必须可回放（同样输入能复现同样路由/结果，至少在工程层面可解释）。
  4. 安全优先：执行层永远不“猜测执行”，权限不足宁可拒绝；高风险动作要二次确认或安全门禁。
  5. 可观测性：trace_id 贯穿感知→决策→执行→回执→日志；能从一次任务还原全链路。
  6. 绿色制造导向：减少无效调用与空转（例如重复解析/重复下发/无意义重试），提升一次成功率，降低能耗与停线风险。

示例架构图（Mermaid，可直接复制修改）：

flowchart LR
  subgraph P[感知层 Perception]
    UI[用户/上位机指令] --> PARSE[指令解析与归一化]
    SENS[现场数据采集] --> VALID[数据校验与融合]
    PARSE --> STATE[结构化状态 PerceivedState]
    VALID --> STATE
  end

  subgraph D[决策层 Decision]
    STATE --> INTENT[意图识别 Intent]
    INTENT --> RULES[规则匹配 RuleMatch]
    RULES --> PLAN[任务规划 DecisionPlan]
    INTENT -->|缺信息/冲突| CLARIFY[澄清/二次确认]
    CLARIFY --> STATE
  end

  subgraph A[执行层 Action]
    PLAN --> GATE[安全门禁/二次确认 Gate]
    GATE --> DISPATCH[任务下发 Dispatch]
    DISPATCH --> ROBOT[机械臂/输送线控制]
    ROBOT --> RECEIPT[回执 ActionReceipt]
    RECEIPT --> STATUS[状态查询/更新]
  end

  subgraph X[横切能力 Cross-cutting]
    AUTHZ[权限校验 AuthZ]
    AUDIT[审计日志 Audit Log]
    OBS[可观测性 Trace/Metric]
  end

  UI -. trace_id .-> OBS
  PARSE -. trace_id .-> OBS
  PLAN -. trace_id .-> OBS
  DISPATCH -. trace_id .-> OBS
  AUTHZ --> GATE
  PLAN --> AUTHZ
  RECEIPT --> AUDIT
  PLAN --> AUDIT

逐段解释与自检：

  1. 把你们组的自选题场景（如苹果分拣）写成三段式模块清单（至少每段 2 个子模块）。
  2. 在架构图上标出三类失败点：缺信息、冲突、执行失败，并写出各自的兜底路径。

快速检查（口头回答即可）：

  1. 你们的 PerceivedState 里有哪些字段？哪些字段缺失时必须澄清？
  2. 你们的执行层如何回执？失败时怎么区分“可重试”与“需人工介入”？

接口契约示例（Python 标准库 dataclass，便于阅读与自检）：

from __future__ import annotations

from dataclasses import dataclass
from typing import Literal, Optional

Intent = Literal["dispatch_sort", "query_status", "query_rules", "clarify", "reject"]
Retryable = Literal["yes", "no"]

@dataclass(frozen=True)
class PerceivedState:
    trace_id: str
    raw_text: str
    item: Optional[str]
    quantity: Optional[int]
    destination: Optional[str]
    priority: Optional[Literal["low", "normal", "high"]]
    constraints: tuple[str, ...]
    missing_fields: tuple[str, ...]

@dataclass(frozen=True)
class DecisionPlan:
    trace_id: str
    intent: Intent
    action_name: str
    payload: dict
    need_confirm: bool

@dataclass(frozen=True)
class ActionReceipt:
    trace_id: str
    ok: bool
    status: Literal["accepted", "running", "done", "failed"]
    error_code: Optional[str]
    error_message: Optional[str]
    retryable: Optional[Retryable]

逐段解释与自检：

  1. 你先写：模块列表 + 关键数据对象名（不要空手让 AI 想象）
  2. 用 AI 生成：架构图 + 契约表初稿（模板 2/3）
  3. 人工审计：用“接口六问”和“架构图自检清单”找问题
  4. 迭代修订：把修改点写回到图与表（形成可交付版本）

建议你们把 AI 输出当作“可编辑草稿”，至少做 3 类审计：

在分拣智能体里，至少有两类标注数据：

  1. 感知层标注：从 raw_text 标注出 slots（item/quantity/destination/constraints）
  2. 决策层标注：从 PerceivedState 标注出 intent 与 rule_hit（意图与规则命中）

推荐数据流图（Mermaid，可复制修改）：

flowchart TB
  subgraph P[感知层]
    RAW[raw_text + sensor_snapshot] --> PS[PerceivedState]
  end

  subgraph L[标注与数据治理]
    RAW --> QUEUE[样本入库 sample_store]
    QUEUE --> LABEL1[槽位标注 slots]
    QUEUE --> LABEL2[意图标注 intent]
    LABEL1 --> DS1[dataset_slots_v*]
    LABEL2 --> DS2[dataset_intent_v*]
  end

  subgraph D[决策层]
    PS --> ROUTE[Intent Router]
    ROUTE --> RULE[Rule Match]
  end

  DS1 -->|上线前/迭代| P
  DS2 -->|上线前/迭代| D

  subgraph A[执行层]
    RULE --> ACT[Dispatch/Control]
    ACT --> REC[ActionReceipt]
  end

  REC -->|回放/复盘| QUEUE

逐段解释与自检：

可运行的最小“样本落盘”示例（标准库，不依赖第三方）：

把下面代码保存为 sample_store_demo.py 后再运行。

import json
import time
import uuid
from pathlib import Path

def append_jsonl(path: Path, record: dict) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    with path.open("a", encoding="utf-8") as f:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")

trace_id = str(uuid.uuid4())
record = {
    "ts_ms": int(time.time() * 1000),
    "trace_id": trace_id,
    "raw_text": "把 3 个苹果放到 A 口，优先级高，注意易碎",
    "sensor_snapshot": {"line": "L1", "robot_state": "idle"},
    "perceived_state": {"item": "苹果", "quantity": 3, "destination": "A", "constraints": ["易碎"], "missing_fields": []},
    "decision": {"intent": "dispatch_sort", "action_name": "dispatch_task", "payload": {"bin": "A", "item": "苹果", "qty": 3}},
    "action_receipt": {"ok": True, "status": "accepted"}
}

append_jsonl(Path("data/sample_store/sorting_samples.jsonl"), record)
print("saved:", trace_id)

逐段解释与自检：

对应运行命令（PowerShell / CMD 均可，示例按 PowerShell 书写）：

python -c "import sys; print(sys.version)"
python sample_store_demo.py

逐条解释与自检：

  1. 为你们的自选题场景补齐一份接口契约表（至少 6 行接口）。
  2. 绘制一张标注数据流图，并明确：样本从哪里来、标注产物去哪里、版本怎么写、trace_id 如何贯穿。

工业级 AI 智能体架构不仅关乎“能用”，更关乎“绿色、可靠、可持续”：

  1. 学习智能体架构设计原则与模块划分方法，完成工作表 1/2/3/4。
  2. 结合分拣/自选题场景，梳理“感知 - 决策 - 执行”各模块的功能与边界，绘制架构草图（建议 Mermaid 或手绘拍照）。
  3. 使用 AI 大模型生成架构设计初稿，进行人工审计并优化模块接口设计，记录修改点与理由。
  4. 梳理数据标注环节在架构中的数据流，绘制简单数据流图（要求含版本与 trace_id）。

作业（布置）

1）提交自选题场景的 AI 智能体架构图（含模块划分、接口定义），附架构设计说明（200 字左右，阐述模块划分依据）。

2）提交 AI 交互记录（生成架构初稿、优化接口设计的全过程），撰写 100 字左右说明，描述对 AI 生成内容的调整思路。

3）梳理数据标注环节在架构中的数据流，绘制简单的数据流图（要求包含样本来源、标注产物、数据集版本与 trace_id 贯穿）。

提交检查清单（提交前自检）：